{Docs} Increase visibility of doc/use_cli_effectively.md #13249
Conversation
jiasli
requested review from
arrownj,
fengzhou-msft,
haroldrandom,
Juliehzl and
qianwens
as code owners
jiasli
requested review from
dbradish-microsoft,
qwordy,
mmyyrroonn,
achandmsft,
yonzhan,
yungezz,
zhoxing-ms and
jsntcy
|
add to S169 |
doc/use_cli_effectively.md
Outdated
| ```sh | ||
| az ad app create --display-name my-native --native-app --required-resource-accesses @manifest.json | ||
| ``` | ||
| 8. When a CLI argument says it accepts a space-separated list, these are the formats accepted: | ||
| - `--arg foo bar`: OK. Unquoted, space-separated list | ||
| - `--arg "foo" "bar"`: OK: Quoted, space-separated list | ||
| - `--arg "foo bar"`: BAD. This is a string with a space in it, not a space-separated list. | ||
| 9. When running Azure CLI commands in PowerShell, parsing errors will occur when the arguments contain special characters of PowerShell, such as at `@`. You can solve this problem by adding `` ` `` before the special character to escape it, or by enclosing the argument with single or double quotes `'`/`"`. For example, `az group deployment create --parameters @parameters.json` dose't work in PowerShell because `@` is parsed as a [splatting symbol](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting). To fix this, you may change the argument to `` `@parameters.json`` or `'@parameters.json'`. | ||
| 9. When running Azure CLI commands in PowerShell, parsing errors will occur when the arguments contain special characters of PowerShell, such as at `@`. You can solve this problem by adding `` ` `` before the special character to escape it, or by enclosing the argument with single or double quotes `'`/`"`. For example, `az group deployment create --parameters @parameters.json` doesn't work in PowerShell because `@` is parsed as a [splatting symbol](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting). To fix this, you may change the argument to `` `@parameters.json`` or `'@parameters.json'`. |
There was a problem hiding this comment.
No idea why the word diff is not rendered.
- dose't
+ doesn't
| az version: error: argument --query: invalid jmespath_type value: 'azure-cli' | ||
|
|
||
| # Correct | ||
| $ az version --query '"azure-cli"' |
There was a problem hiding this comment.
I suggest either call out that this is corerct on Linux/Mac only or put the correct commands on windows command prompt and powershell as well.
There was a problem hiding this comment.
Nice one, added as requested. The quoting rules for Command Prompt are also mentioned in item 4. As for PowerShell, the format is weird due to a known bug which I further described in #13419.
There was a problem hiding this comment.
@jiasli , my grammatic comments have been added as requested.
| @@ -86,18 +87,31 @@ For scripting purposes, we output certain exit codes for differing scenarios. | |||
| |2 |Parser error; check input to command line. | | |||
| |3 |Missing ARM resource; used for existence check from `show` commands. | | |||
|
|
|||
| #### More Samples and Snippets | |||
| For more usage examples, take a look at our [GitHub samples repo](http://github.com/Azure/azure-cli-samples) or [https://docs.microsoft.com/cli/azure/overview](https://docs.microsoft.com/cli/azure/overview). | |||
| ### Common scenarios and use Azure CLI effectively | |||
There was a problem hiding this comment.
The "and" makes this sentence a little confusing. Are "common scenarios" and using "Azure CLI effectively two different things? Consider "that".
###Common scenarios that use Azure CLI effectively
There was a problem hiding this comment.
I think the contents of this section focuses on both aspects: common scenarios AND instructions for users to use CLI effectively. Not all scenarios are using CLI effectively. Some are for issue workarounds or troubleshooting.
doc/use_cli_effectively.md
Outdated
|
|
||
| ## REST API command - `az rest` | ||
|
|
||
| If neither generic update arguments nor `az resource` meets your needs, you can use `az rest` command to call the REST API. It automatically authenticates using the credential logged in and sets header `Content-Type: application/json`. |
There was a problem hiding this comment.
consider, instead of "using the credential logged in" to "using the logged-in credential"
"and sets header" to "and sets the header to"
There was a problem hiding this comment.
| If neither generic update arguments nor `az resource` meets your needs, you can use `az rest` command to call the REST API. It automatically authenticates using the credential logged in and sets header `Content-Type: application/json`. | |
| If neither generic update arguments nor `az resource` meets your needs, you can use `az rest` command to call the REST API. It automatically authenticates using the logged-in credential and sets header `Content-Type: application/json`. |
As for the header, it is setting one of the header entries, instead of setting all header entries.
Thank you so much @dbradish-microsoft, I have applied most of those changes. For the rest, I have provided some explanations. |
Description
doc/use_cli_effectively.md, thus avoiding issues likeaz restcannot parse json body #9742az rest--queryIn order to be consistent with public docs like Create an Azure service principal with the Azure CLI,
Testing Guide
View the rendered file by clicking View file.
Remark
⚠ Renaming the titles may break anchors in previous issues, without any workarounds or redirection, but this is inevitable in order to be more friendly to future readers.